From 2f0d43aa816847d67d155e6b3097c3e9da0c508f Mon Sep 17 00:00:00 2001
From: masoodafar-web <masoud.afarin.moghaddam@outlook.com>
Date: Thu, 19 Feb 2026 02:17:10 +0330
Subject: [PATCH] docs: clarify Magic Wallet cap is per-cycle, not lifetime
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Cap resets every time user buys a new 56M package and re-enters Magic
- MagicTotalDeposited & MagicTotalCredited reset to 0 on each new cycle
- Added multi-cycle example (cycle 1, 2, 3... ∞)
- Added section 4.3: reset behavior on re-entry
- Added test scenarios for cycle reset
- PurchaseCycleCount tracks cycles but has no limit
---
 roadmap/MAGIC-WALLET-PLAN.md |  2 +
 roadmap/MAGIC-WALLET-SPEC.md | 72 +++++++++++++++++++++++++++++++-----
 2 files changed, 64 insertions(+), 10 deletions(-)

diff --git a/roadmap/MAGIC-WALLET-PLAN.md b/roadmap/MAGIC-WALLET-PLAN.md
index bf44aa2..5a0bf44 100644
--- a/roadmap/MAGIC-WALLET-PLAN.md
+++ b/roadmap/MAGIC-WALLET-PLAN.md
@@ -47,6 +47,8 @@
 - سناریو ۱: Balance=0 بعد از خرید → WalletMode=Magic ✅
 - سناریو ۲: بدون پکیج + Balance=0 → نباید Magic بشه ❌
 - سناریو ۳: Magic + Balance=0 + TotalDeposited>0 → خروج ✅
+- سناریو ۴: خروج از Magic → خرید مجدد پکیج → Balance=0 → Magic مجدد با **سقف ریست‌شده** ✅
+- سناریو ۵: دور دوم → TotalDeposited, TotalCredited = 0 (ریست) ✅
 
 ---
 
diff --git a/roadmap/MAGIC-WALLET-SPEC.md b/roadmap/MAGIC-WALLET-SPEC.md
index 1e66ba3..7188caf 100644
--- a/roadmap/MAGIC-WALLET-SPEC.md
+++ b/roadmap/MAGIC-WALLET-SPEC.md
@@ -10,6 +10,8 @@
 
 کاربر بعد از خرید پکیج پایه (۵۶M) و خرج کردن کامل Balance از فروشگاه عادی، وارد **حالت جادویی** می‌شه. در این حالت می‌تونه کیف‌پولش رو از درگاه شارژ کنه و **۲.۵ برابر** اعتبار بگیره — بدون هیچ کمیسیون یا پورسانتی.
 
+> ⚠️ **سقف ۱۰۰M ورودی / ۲۵۰M خروجی per-cycle هست** — هر بار که کاربر دوباره پکیج ۵۶M بخره و وارد Magic بشه، سقف ریست میشه. این چرخه تا بی‌نهایت تکرار میشه.
+
 ```mermaid
 stateDiagram-v2
     [*] --> NewUser: ثبت‌نام
@@ -77,16 +79,19 @@ stateDiagram-v2
 
 ## ۳. قوانین Magic Mode
 
-### ۳.۱ ضریب و سقف
+### ۳.۱ ضریب و سقف (per-cycle)
 
-| پارامتر | مقدار | ثابت پیشنهادی |
-|----------|-------|---------------|
-| ضریب شارژ | **×2.5** | `MagicWalletMultiplier = 2.5m` |
-| سقف ورودی | **100M تومان** (1B ریال) | `MagicWalletMaxDeposit = 1_000_000_000` |
-| سقف خروجی | **250M تومان** (2.5B ریال) | `MagicWalletMaxCredit = 2_500_000_000` |
-| سود کاربر | **150%** | — |
+| پارامتر | مقدار | ثابت پیشنهادی | اسکوپ |
+|----------|-------|---------------|--------|
+| ضریب شارژ | **×2.5** | `MagicWalletMultiplier = 2.5m` | — |
+| سقف ورودی | **100M تومان** (1B ریال) | `MagicWalletMaxDeposit = 1_000_000_000` | **هر دور** |
+| سقف خروجی | **250M تومان** (2.5B ریال) | `MagicWalletMaxCredit = 2_500_000_000` | **هر دور** |
+| سود کاربر | **150%** | — | — |
 
-### ۳.۲ مثال عددی
+> 🔄 **سقف per-cycle هست نه lifetime.** هر بار که کاربر از Magic خارج بشه و دوباره پکیج ۵۶M بخره،
+> `MagicTotalDeposited` و `MagicTotalCredited` به **صفر ریست** میشن و یه دور جدید شروع میشه.
+
+### ۳.۲ مثال عددی (یک شارژ)
 
 ```
 واریز: 10,000,000 تومان (100M ریال)
@@ -95,13 +100,45 @@ stateDiagram-v2
   ├── اعتبار نهایی:    25,000,000 تومان   (Balance += 250M ریال)
   └── WalletChangeLog:  BalanceChange = +250,000,000 ریال ✅
 
-سقف:
+سقف (این دور):
   ├── مجموع واریزی:    MagicTotalDeposited += 100,000,000 ریال
   ├── مجموع اعتبار:    MagicTotalCredited  += 250,000,000 ریال  
   └── باقیمانده سقف:    MaxDeposit - TotalDeposited
 ```
 
-### ۳.۳ چه چیزهایی غیرفعال میشه
+### ۳.۳ مثال چند دوری (چرخه تکرار)
+
+```
+══════════════════════════════════════════════════════════════
+  دور ۱ (اولین بار)
+══════════════════════════════════════════════════════════════
+  ① خرید پکیج 56M (IPG یا دایا) → Balance=56M, Discount=112M
+  ② فعال‌سازی باشگاه → کمیسیون ✅
+  ③ خرید از فروشگاه عادی → Balance کم میشه...
+  ④ Balance = 0 → 🪄 Magic Mode فعال!
+     MagicTotalDeposited = 0 (ریست)
+  ⑤ شارژ جادویی: مجموعاً 100M واریز → 250M اعتبار
+  ⑥ خرید از فروشگاه عادی → Balance کم میشه...
+  ⑦ Balance = 0 → خروج از Magic → Normal Mode
+
+══════════════════════════════════════════════════════════════
+  دور ۲ (خرید مجدد پکیج — فقط IPG، دایا ❌)
+══════════════════════════════════════════════════════════════
+  ① خرید پکیج 56M (فقط IPG) → Balance=56M, Discount=112M
+  ② کمیسیون دوباره فعال ✅
+  ③ خرید از فروشگاه عادی → Balance کم میشه...
+  ④ Balance = 0 → 🪄 Magic Mode فعال!
+     MagicTotalDeposited = 0 (ریست)
+                          ─────────
+  ⑤ شارژ جادویی: مجموعاً 100M واریز → 250M اعتبار
+  ⑥ خرید → Balance = 0 → خروج از Magic
+
+══════════════════════════════════════════════════════════════
+  دور ۳, ۴, ۵, ... (تا بی‌نهایت — همین چرخه تکرار)
+══════════════════════════════════════════════════════════════
+```
+
+### ۳.۴ چه چیزهایی غیرفعال میشه
 
 | قابلیت | Normal Mode | Magic Mode |
 |--------|-------------|------------|
@@ -145,6 +182,21 @@ stateDiagram-v2
   └── user.PurchaseCycleCount++
 ```
 
+### ۴.۳ ریست سقف در دور بعدی
+
+```
+وقتی کاربر دوباره پکیج ۵۶M بخره و Balance=0 بشه → Magic Mode:
+  ├── MagicTotalDeposited = 0    ← ریست!
+  ├── MagicTotalCredited = 0     ← ریست!
+  ├── MagicActivatedAt = now     ← زمان جدید
+  └── MagicCompletedAt = null    ← پاک میشه
+
+⚠️ سقف per-cycle هست:
+  ├── هر دور: حداکثر 100M واریز → 250M اعتبار
+  ├── تعداد دور: بی‌نهایت (تا وقتی پکیج بخره)
+  └── PurchaseCycleCount: فقط برای ترک تعداد دورها (محدودیت نداره)
+```
+
 ---
 
 ## ۵. تراکنش‌ها و لاگ