Add server-authoritative RZ Coin rewards

docs/QUESTION_BANK_GAMIFICATION.md

@@ -155,10 +155,10 @@ social notifications.
 
 ### Phase 1: foundation
 
-1. Define the mastery model and expose topic-level progress.
-2. Add server-authoritative RZ Coin awards for approved learning events.
-3. Add user-selected session goals and an end-of-session summary.
-4. Add daily missions with one replacement per day.
+- [x] Define the mastery model and expose topic-level progress.
+- [x] Add server-authoritative RZ Coin awards for approved learning events.
+- [ ] Add user-selected session goals and an end-of-session summary.
+- [ ] Add daily missions with one replacement per day.
 
 ### Phase 2: progression
 

docs/QUESTION_COMPLETION_CREDITS.md

@@ -1,19 +1,22 @@
 # Question-completion credits
 
-This branch introduces credit earning only. It does not impose a question
-limit, redeem credits, sell products, activate passes, consume exam tokens, or
-reset QBank progress.
+RZ Coin is awarded by the API for verified learning outcomes. The client displays
+award results but cannot choose award amounts or reason codes.
 
-- A successfully stored first answer earns one credit regardless of whether it
-  is correct.
-- A repeated answer does not earn another credit.
-- A skipped question does not earn credit.
-- At most 20 credits can be earned in a rolling 24-hour window.
+- A first correct answer earns 1 coin at difficulty 1-3, 2 at difficulty 4,
+  and 3 at difficulty 5.
+- A correct scheduled review earns 1 coin, or 3 when it recovers a miss after
+  at least 24 hours.
+- First-time system promotions to Practicing, Strong, and Mastered earn 3, 5,
+  and 10 coins. Completing a real exam simulation earns 10 coins.
+- Incorrect answers, skips, repeated submissions, and sample simulations earn nothing.
+- Repeatable question and review rewards are capped at 30 coins in a rolling
+  24-hour window; milestone and simulation awards are outside that cap.
 - Historical attempts are not backfilled.
 - `GET /api/credits` returns the authenticated user's balance and current
   rolling-window capacity.
 - The first-attempt response also includes the updated credit status.
 
-The API is authoritative. Credit grants use the immutable attempt ID as their
-idempotency key, so retrying the same completed question cannot grant another
-credit. Credit accounts are included in account export and deletion.
+The API is authoritative. Immutable attempt, review, simulation, and mastery
+identifiers make grants idempotent. Awards and purchases appear in the user's
+coin ledger. Credit accounts are included in account export and deletion.