docs: measured model price ledger (docs/model-prices.md)

What GapGPT actually billed per model, with dates and evidence, so a
later price rise can be compared with what it was. gpt-4.1-mini and
gpt-4o-mini were re-checked from the 852 recorded calls in
docs/benchmarks/2026-09-26-tutor-model: every call equals the official
OpenAI per-token price or less (input cache), none more.

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

CLAUDE.md

@@ -258,6 +258,9 @@ island of every unit. Details in `docs/architecture.md`.
 
 ## AI provider notes
 
+**Measured prices live in `docs/model-prices.md`** — a ledger of what GapGPT actually billed per
+model, with dates and evidence. When a price changes, add a row there; never overwrite the old one.
+
 `OPENAI_BASE_URL` points at GapGPT (an OpenAI proxy reachable from Iran) and it exposes
 ~127 models, including reasoning ones. Two failures look alike and must not be treated
 alike — `is_account_limit()` in `rag_verify_solutions` is the shared guard:

docs/model-prices.md

@@ -0,0 +1,71 @@
+# دفترِ قیمتِ مدل‌ها (اندازه‌گیری‌شده، نه از جدولِ قیمت)
+
+این فایل یک دفتر است: هر بار قیمت یا مدل عوض شد، **ردیفِ تازه اضافه کنید و ردیفِ قدیمی را پاک
+نکنید.** هدف این است که اگر GapGPT یا OpenAI روزی قیمت را بالا برد، بشود دید قبلاً چه بوده، از
+کِی عوض شده، و هر عدد با چه آزمایشی به دست آمده.
+
+همه‌ی قیمت‌ها به **دلارِ آمریکا** هستند. «سنت» یعنی یک‌صدمِ دلار. تبدیل به تومان در
+`docs/ai-cost-and-guardrails.md` است، چون نرخِ دلار جدا از قیمتِ مدل عوض می‌شود.
+
+## مدل‌هایی که الان استفاده می‌شوند
+
+| کار | مدل | تنظیم | از کِی |
+|---|---|---|---|
+| جوابِ دستیار (چت) | `gpt-4.1-mini` | `OPENAI_CHAT_MODEL` | ۲۰۲۶-۰۹-۲۶ (پیش از آن `gpt-4o-mini`) |
+| خواندنِ صفحه‌ی کتاب (vision) | `gpt-4.1-mini` | `OPENAI_VISION_MODEL` | ۲۰۲۶-۰۹-۲۰ |
+| embedding برای Qdrant | `text-embedding-3-small` | `OPENAI_EMBEDDING_MODEL` | از ابتدا |
+
+همه از راهِ GapGPT (`OPENAI_BASE_URL`) صدا زده می‌شوند. کلید با سرورِ زنده و تیمِ دیگر مشترک است.
+
+## قیمتِ هر توکن، همان‌طور که GapGPT واقعاً حساب کرد
+
+| تاریخِ سنجش | مدل | ورودی (دلار / ۱ میلیون توکن) | خروجی (دلار / ۱ میلیون توکن) | مدرک |
+|---|---|---|---|---|
+| ۲۰۲۶-۰۹-۲۵/۲۶ | `gpt-4.1-mini` | ۰٫۴۰ | ۱٫۶۰ | ۵۴۱ فراخوانی (۱) |
+| ۲۰۲۶-۰۹-۲۵/۲۶ | `gpt-4o-mini` | ۰٫۱۵ | ۰٫۶۰ | ۳۱۱ فراخوانی (۱) |
+
+(۱) `docs/benchmarks/2026-09-26-tutor-model/*.json`: هر جواب `promptTokens`، `completionTokens` و
+`costUsd` دارد، و `costUsd` همان `usage.cost`ی است که خودِ GapGPT برگرداند. در ۲۰۲۶-۱۰-۰۲ دوباره
+حساب شد. برای `gpt-4.1-mini`، ۳۹۰ فراخوانی دقیقاً برابرِ `(0.40 × ورودی + 1.60 × خروجی) / 1e6`
+بودند و ۱۵۱ فراخوانیِ دیگر (۲۸٪) ارزان‌تر، چون کشِ خودکارِ ورودی خورده بودند. هیچ فراخوانی‌ای
+گران‌تر نبود. برای `gpt-4o-mini`، ۲۹۷ فراخوانی دقیقاً برابر بودند و ۱۴ فراخوانی ارزان‌تر.
+**یعنی برای این دو مدل در آن تاریخ، قیمتِ GapGPT همان قیمتِ رسمیِ OpenAI بود.**
+
+این را به همه‌ی مدل‌ها تعمیم ندهید: برای ورودِ کتاب، `gemini-3.6-flash` سه برابرِ `gpt-4o` تمام شد،
+یعنی خلافِ چیزی که از جدولِ قیمت انتظار می‌رفت (`docs/extraction-playbook.md`، بخشِ ۱).
+
+## هزینه‌ی هر کار (اندازه‌گیری‌شده)
+
+| تاریخ | کار | مدل | هزینه | چطور اندازه گرفته شد |
+|---|---|---|---|---|
+| ۲۰۲۶-۰۹-۲۰ | خواندنِ یک صفحه‌ی کتاب | `gpt-4.1-mini` | ۰٫۲۲ سنت | `/dashboard/billing/usage` پیش و پس از ۳ صفحه |
+| ۲۰۲۶-۰۹-۲۰ | خواندنِ یک صفحه‌ی کتاب | `gpt-4o` | ۰٫۷۷ سنت | همان |
+| ۲۰۲۶-۰۹-۲۰ | خواندنِ یک صفحه‌ی کتاب | `gemini-3.6-flash` | ۲٫۱۳ سنت | همان |
+| ۲۰۲۶-۰۹-۲۰ | ساختِ یک سوالِ چهارگزینه‌ای | `o4-mini` | ۰٫۷۷ سنت | همان |
+| ۲۰۲۶-۰۹-۲۵ | یک جوابِ دستیار، پرامپتِ v3 | `gpt-4o-mini` | ۰٫۰۴۴ سنت | `rag_model_benchmark` |
+| ۲۰۲۶-۰۹-۲۵ | یک جوابِ دستیار، پرامپتِ v3 | `gpt-4.1-mini` | ۰٫۱۱۶ سنت | همان |
+| ۲۰۲۶-۰۹-۲۵ | یک جوابِ دستیار، پرامپتِ v3 | `gpt-5-mini` | ۰٫۱۷۱ سنت | همان |
+| ۲۰۲۶-۰۹-۲۵ | یک جوابِ دستیار، پرامپتِ v3 | `gpt-5.4-mini` | ۰٫۲۹ سنت | همان |
+| ۲۰۲۶-۰۹-۲۵ | یک جوابِ دستیار، پرامپتِ v3 | `o4-mini` | ۰٫۴۱ سنت | همان |
+| ۲۰۲۶-۰۹-۲۶ | میانگینِ همه‌ی جواب‌های سنجش | `gpt-4.1-mini` | ۰٫۰۹۶ سنت | میانگینِ `costUsd`ِ ۵۴۱ فراخوانی (۱) |
+| ۲۰۲۶-۱۰-۰۱ | یک جوابِ دستیار، پرامپتِ `tutor-v11-math-only`، ۱۰۳ مسئله‌ی کتاب | `gpt-4.1-mini` | ۰٫۱۶۲ سنت (دبستان ۰٫۱۲۹، دبیرستان ۰٫۲۲۵) | توکنِ ورودی تخمینی (۰٫۳۸۷ توکن به ازای هر حرف)، خروجی از جوابِ واقعی، ضربدر قیمتِ بالا |
+| ۲۰۲۶-۱۰-۰۱ | یک سوالِ زنده در اپ (۱۲ سوال) | `gpt-4.1-mini` | ۰٫۲۲۵ سنت | فراخوانیِ واقعی |
+
+عددِ برنامه‌ریزیِ قیمت‌گذاری **۰٫۲۰ سنت برای هر سوالِ دستیار** است و حدودِ ۷۰٪ِ آن ورودی است.
+هزینه‌ی embedding جدا اندازه گرفته نشده است. قیمتِ رسمیِ `text-embedding-3-small` بسیار کمتر از
+چت است، ولی این را روی GapGPT نسنجیده‌ایم.
+
+## وقتی قیمت عوض شد یا شک کردید
+
+۱. **هزینه‌ی واقعیِ اپ، بی‌خرج:** از ۲۰۲۶-۱۰-۰۱ هر جوابِ دستیار `prompt_tokens` و
+`completion_tokens` را روی `ai_tutor.Message` ذخیره می‌کند. جمعِ توکن‌های یک بازه را در قیمتِ
+این فایل ضرب کنید (پرس‌وجو در `docs/ai-cost-and-guardrails.md`).
+
+۲. **قیمتِ امروزِ GapGPT، با چند سنت:** یک سوالِ کوتاه بفرستید و `usage.cost` را با
+`(ورودی × قیمتِ ورودی + خروجی × قیمتِ خروجی) / 1e6` مقایسه کنید. اگر نخواند، قیمت عوض شده است.
+موجودی را پیش و پس با `/dashboard/billing/usage` بسنجید (`rag_model_benchmark._usage_cents`)؛
+این تنها عددِ قابلِ اتکاست، چون `hard_limit_usd` موجودی نیست.
+
+۳. **ردیفِ تازه اضافه کنید**، با تاریخ، مدل، عدد و مدرک. ردیفِ قدیمی را نگه دارید. اگر قیمتِ
+دستیار عوض شد، قیمتِ بسته‌ها (`subscription.0010`) را هم دوباره بسنجید: سهمِ هزینه از درآمدِ هر
+بسته در `docs/ai-cost-and-guardrails.md` با همین عددها حساب شده است.