From b1dd69b31fb61d3249de6fcb2179adb17c7fcaa3 Mon Sep 17 00:00:00 2001
From: masoodafar-web <masoud.afarin.moghaddam@outlook.com>
Date: Thu, 19 Feb 2026 02:32:04 +0330
Subject: [PATCH] =?UTF-8?q?docs:=20fix=20Magic=20Mode=20exit=20condition?=
 =?UTF-8?q?=20=E2=80=94=20BOTH=20Balance=3D0=20AND=20cap=20reached?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Exit requires BOTH simultaneously: Balance==0 AND TotalDeposited>=100M
- If Balance=0 but cap not reached → still Magic (can charge more)
- If cap reached but Balance>0 → still Magic (can spend more)
- Added examples: partial deposit (50M/100M) stays in Magic
- Fixed handler 8.1 pseudo-code
- Updated test scenarios in PLAN (7 scenarios covering edge cases)
---
 roadmap/MAGIC-WALLET-PLAN.md |  8 +++++---
 roadmap/MAGIC-WALLET-SPEC.md | 25 +++++++++++++++++++++----
 2 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/roadmap/MAGIC-WALLET-PLAN.md b/roadmap/MAGIC-WALLET-PLAN.md
index 5a0bf44..57b457c 100644
--- a/roadmap/MAGIC-WALLET-PLAN.md
+++ b/roadmap/MAGIC-WALLET-PLAN.md
@@ -46,9 +46,11 @@
 **تست:** 
 - سناریو ۱: Balance=0 بعد از خرید → WalletMode=Magic ✅
 - سناریو ۲: بدون پکیج + Balance=0 → نباید Magic بشه ❌
-- سناریو ۳: Magic + Balance=0 + TotalDeposited>0 → خروج ✅
-- سناریو ۴: خروج از Magic → خرید مجدد پکیج → Balance=0 → Magic مجدد با **سقف ریست‌شده** ✅
-- سناریو ۵: دور دوم → TotalDeposited, TotalCredited = 0 (ریست) ✅
+- سناریو ۳: Magic + Balance=0 + **TotalDeposited=50M** (سقف پر نشده) → **هنوز Magic!** نباید خارج بشه ❌
+- سناریو ۴: Magic + Balance=0 + **TotalDeposited=100M** (سقف پر) → خروج ✅
+- سناریو ۵: Magic + Balance=30M + TotalDeposited=100M → **هنوز Magic!** (بالانس داره) ❌
+- سناریو ۶: خروج از Magic → خرید مجدد پکیج → Balance=0 → Magic مجدد با **سقف ریست‌شده** ✅
+- سناریو ۷: دور دوم → TotalDeposited, TotalCredited = 0 (ریست) ✅
 
 ---
 
diff --git a/roadmap/MAGIC-WALLET-SPEC.md b/roadmap/MAGIC-WALLET-SPEC.md
index 7188caf..b428e35 100644
--- a/roadmap/MAGIC-WALLET-SPEC.md
+++ b/roadmap/MAGIC-WALLET-SPEC.md
@@ -172,14 +172,28 @@ stateDiagram-v2
 ### ۴.۲ خروج از Magic Mode
 
 ```
-شرط‌ها (هرکدام کافیه):
-  ├── wallet.Balance == 0 && MagicTotalDeposited > 0   (همه رو خرج کرد)
-  └── MagicTotalDeposited >= MagicWalletMaxDeposit      (سقف پر شد)
+شرط‌ها (هر دو باید همزمان true باشن):
+  ├── wallet.Balance == 0                              (همه رو خرج کرده)
+  └── wallet.MagicTotalDeposited >= MagicWalletMaxDeposit  (سقف 100M پر شده)
 
 نتیجه:
   ├── wallet.WalletMode = Normal
   ├── wallet.MagicCompletedAt = DateTime.UtcNow
   └── user.PurchaseCycleCount++
+
+⚠️ توضیح مهم:
+  اگه Balance=0 بشه ولی هنوز سقف شارژ پر نشده → هنوز Magic هست!
+  کاربر میتونه دوباره شارژ کنه (تا سقف 100M).
+  
+  مثال:
+    TotalDeposited = 50M, Balance = 0
+    → هنوز Magic → میتونه 50M دیگه شارژ کنه (125M اعتبار بگیره)
+    
+    TotalDeposited = 100M, Balance = 30M
+    → هنوز Magic → نمیتونه شارژ کنه ولی هنوز بالانس داره
+    
+    TotalDeposited = 100M, Balance = 0
+    → ✅ خروج از Magic → Normal Mode
 ```
 
 ### ۴.۳ ریست سقف در دور بعدی
@@ -352,10 +366,13 @@ Migration: AddMagicWalletFields
 
   if (wallet.WalletMode == Magic 
       && wallet.Balance == 0 
-      && wallet.MagicTotalDeposited > 0)
+      && wallet.MagicTotalDeposited >= SystemConstants.MagicWalletMaxDeposit)
   {
       → خروج از Magic Mode
+      // سقف 100M پر شده + همه رو خرج کرده
   }
+  // ⚠️ اگه Balance=0 ولی سقف پر نشده → هنوز Magic!
+  // کاربر میتونه دوباره شارژ کنه
 ```
 
 ### ۸.۲ CalculateWeeklyBalancesCommandHandler (تغییر)