docs: question packs, credit rules, real hearts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/ai-cost-and-guardrails.md

@@ -31,21 +31,40 @@ Message.objects.filter(role='assistant', created_at__gte=since).values('conversa
     .annotate(p=Sum('prompt_tokens'), c=Sum('completion_tokens'))   # سنت = (0.4p + 1.6c) / 1e4
 ```
 
-## سقفِ روزانه
+## بسته‌ی سوال و سقفِ روزانه (از ۲۰۲۶-۱۰-۰۲)
 
-- رایگان: `AI_DAILY_QUOTA_FREE` در `.env`، پیش‌فرض **۳**. تا ۲۰۲۶-۱۰-۰۱ همه، با اشتراک یا بی‌اشتراک،
-  ۱۵ سوال در روز داشتند.
-- مشترک: `Plan.ai_daily_quota`، در ادمین قابلِ ویرایش و پیش‌فرض ۱۵. اشتراکِ بی‌پلن (هدیه) هم ۱۵
-  می‌گیرد. کد در `subscription.services.ai_daily_quota` است.
-- کاربرِ رایگانی که به سقف می‌رسد پیامِ «با خریدِ اشتراک…» می‌گیرد و اپ دکمه‌ی «دیدنِ اشتراک‌ها»
-  را نشان می‌دهد.
-- قیمتِ فعلی (migrationِ `subscription.0008`): ماهانه ۱۷۹٬۰۰۰ و سالانه ۱٬۷۹۰٬۰۰۰ تومان، هر دو ۱۰ سوال در
-  روز. ۵ سوال (`0007`) در برابرِ ۳ِ رایگان تفاوتی حس نمی‌شد. با هزینه‌ی ~۶۰۰ تومان برای هر سوال و مصرفِ
-  یک‌سومِ سقف، ۱۰ سوال حدودِ ~۱۷۶ هزار تومان در ماه می‌خواهد تا دستیار حداکثر ۴۰٪ِ درآمدِ خالص (پس از ۱۵٪یِ
-  بازار) باشد؛ ۱۵ سوال ~۲۶۵ هزار. خرجِ کاربرهای رایگان به ازای هر مشترک با درصدِ تبدیل تغییر می‌کند: با ۵٪
-  تبدیل و میانگینِ ۵ سوال در ماه برای هر رایگان، ~۵۷ هزار تومان؛ زیرِ ۵٪ از خرجِ خودِ مشترک بیشتر می‌شود.
-  API پلن‌ها `aiDailyQuota` و `freeAiDailyQuota` می‌دهد و کارتِ پلن عدد را از همین می‌سازد.
-- انتخابِ عددها تصمیمِ محصولی است. جدولِ قیمت در برابرِ سقف در نسخه‌ی کاملِ گزارش آمده است.
+اشتراکِ ماهانه/سالانه کنار رفت و **بسته‌ی سوال** جایش آمد (`subscription.0009`، `subscription.0010`):
+
+| بسته | قیمت (تومان) | هر سوال | هدیه | سهمِ هزینه از درآمدِ خالص (میانگین / دبیرستان) |
+|---|---|---|---|---|
+| ۲۰ سوال | ۴۵٬۰۰۰ | ۲٬۲۵۰ | ۷ روز قلبِ نامحدود | ۳۱٪ / ۴۰٪ |
+| ۶۰ سوال | ۱۱۹٬۰۰۰ | ۱٬۹۸۰ | ۳۰ روز | ۳۶٪ / ۴۶٪ |
+| ۱۵۰ سوال | ۲۵۹٬۰۰۰ | ۱٬۷۳۰ | ۶۰ روز | ۴۱٪ / ۵۲٪ |
+
+سهم‌ها پس از ۱۵٪یِ کافه‌بازار حساب شده‌اند. چرا بسته: همه هر روز نمی‌آیند، ۱۷۹ هزار تومان در ماه برای خیلی‌ها زیاد
+بود، و مشترکِ پرکار زیان می‌ساخت. با بسته هر سوال جدا سود دارد. مسیرِ قیمت‌ها پیش از این:
+- سالانه ۲۹۹ هزار تومان، با ۱۵ سوال در روز برای همه.
+- ماهانه/سالانه ۹۹ و ۹۹۰ هزار تومان، با ۵ سوال در روز.
+- ماهانه/سالانه ۱۷۹ و ۱٬۷۹۰ هزار تومان، با ۱۰ سوال در روز.
+
+پلن‌های اشتراکی پاک نشدند (`on_sale=False`) تا مشترکِ فعلی سقفش را نگه دارد.
+
+- **ترتیبِ خرج:** اول `AI_DAILY_QUOTA_FREE` سوالِ رایگانِ همان روز (پیش‌فرض ۳)، بعد اعتبارِ بسته؛ مشترکِ
+  قدیمی سقفِ `Plan.ai_daily_quota`ِ خودش را دارد.
+- **چه چیزی خرج می‌شود:** هر سوالی که به API برسد، از جمله ردِ «غیرِ ریاضی» توسطِ مدل. ردِ صافیِ سرور،
+  جوابِ کش‌شده و جوابی که ساخته نشد چیزی کم نمی‌کنند. `Message.charge` روی هر پیامِ کاربر می‌گوید
+  سوال از کجا پرداخت شد (`free` / `credit` / `none`).
+- **دفترِ اعتبار** `subscription.QuestionCredit`: هر خرید یک ردیفِ مثبت دارد (هر سفارش فقط یک بار، با
+  قیدِ یکتا) و هر سوال یک ردیفِ ۱−. کم شدن داخلِ همان تراکنشی است که ردیفِ کاربر را قفل می‌کند. دو
+  سوالِ هم‌زمان با یک اعتبار آزموده نشده است؛ جلوگیری به آن قفل و `transaction_mode: IMMEDIATE`ِ
+  SQLite سپرده شده.
+- **قلبِ نامحدودِ بسته** در `HeartsPass` است، جدا از `Subscription`، تا خریدِ بسته اشتراکِ کسی را عوض
+  نکند. از پایانِ کارتِ قبلی ادامه پیدا می‌کند. `HEARTS_ENFORCED` حالا پیش‌فرض روشن است، پس قلبِ صفر
+  واقعاً جلوی جواب را می‌گیرد.
+- اپ موجودی را از `GET /api/ai/quota` می‌خواند و بعد از هر جواب از `remainingQuota` و `credits`ِ خودِ
+  جواب. صفحه‌ی خرید `GET /api/subscription/status` (`questionCredits`، `unlimitedHeartsUntil`) را می‌خواند.
+- **کافه‌بازار:** هر بسته باید در پنلِ بازار «محصولِ مصرفی» تعریف شود و اپِ اندروید بعد از تأیید
+  consume کند. این هنوز انجام نشده است.
 
 ## محافظِ دستیار (`rag/services/guardrails.py`)