docs: Magic Wallet + VAT 10% documentation update

- All 14 totalDoc files updated with Magic Wallet additions
- MAGIC-WALLET-PLAN.md: Phase 1-6 checklist fully marked complete
- Business docs: Magic Wallet section, commission filter, new entities
- Payment docs: VAT 9%→10%, TransactionType 14+15, ZarinPal 4th usage
- Technical docs: UserWallet fields, ClubMembershipCycle, gRPC RPCs
- Overview docs: Magic flowchart, ER diagram, changelog, glossary, roadmap

business/BUSINESS-01-CLUB-COMMISSION.md

@@ -1,7 +1,7 @@
 # 🏆 سیستم باشگاه، کمیسیون و درخت شبکه‌ای
 
 > **منابع ادغام‌شده:** `club-commission-system-complete.md`, `balance-calculation-rules.md`, `club-membership-contract-system.md`  
-> **آخرین بروزرسانی:** اسفند ۱۴۰۴
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet + کمیسیون)
 
 ---
 
@@ -13,6 +13,8 @@
 | **درخت باینری** | هر کاربر حداکثر ۲ فرزند مستقیم (چپ/راست) — بدون محدودیت عمق |
 | **کمیسیون هفتگی** | محاسبه بر اساس تعادل چپ/راست — یکشنبه ۰۰:۰۵ (Hangfire cron) |
 | **۳ کیف پول** | `Balance` (نقدی) + `NetworkBalance` (طلایی/کمیسیون) + `DiscountBalance` (تخفیفی) |
+| **کیف‌پول جادویی** | وقتی Balance=0 → حالت Magic فعال → شارژ ×2.5 → سقف 100M/دور |
+| **چرخه عضویت** | `ClubMembershipCycle` — هر خرید پکیج = یک دور جدید (برای تاریخ کمیسیون) |
 
 ---
 
@@ -105,6 +107,21 @@ flowchart LR
 
 > فرمت هفته: `YYYY-Www` (شمسی، شنبه‌پایه)
 
+### ۴.۴ فیلتر کاربران Magic از کمیسیون
+
+> ⚠️ **کاربرانی که در حالت Magic هستند (`WalletMode = 1`) از محاسبات کمیسیون هفتگی خارج می‌شوند.**
+
+```
+فیلتر در ۳ نقطه:
+  ✅ CalculateWeeklyBalancesCommandHandler.cs  →  WHERE wallet.WalletMode != Magic
+  ✅ OrmCommissionCalculationStrategy.cs       →  فیلتر LINQ
+  ✅ sp_CalculateWeeklyBalances.sql            →  NOT EXISTS (WalletMode=1)
+
+تاریخ محاسبه:
+  قبل:  ClubMembership.ActivatedAt (مشکل: بعد از خرید مجدد overwrite می‌شد)
+  بعد:  ClubMembershipCycle.PackagePurchasedAt (هر دور تاریخ مستقل)
+```
+
 ---
 
 ## ۵. تنظیمات سیستمی (SystemConstants)
@@ -120,6 +137,9 @@ flowchart LR
 | `MaxDirectChildrenPerLeg` | 1 | حداکثر فرزند مستقیم هر پا |
 | `MinimumWithdrawAmount` | 1,000,000 | حداقل مبلغ برداشت (ریال) |
 | `ShopVAT` | 0.1 (10%) | مالیات ارزش افزوده |
+| `MagicWalletMultiplier` | 2.5 | ضریب شارژ جادویی (واریز × 2.5) |
+| `MagicWalletMaxDeposit` | 1,000,000,000 | سقف واریز هر دور (100M تومان = 1B ریال) |
+| `MagicWalletMaxCredit` | 2,500,000,000 | سقف اعتبار هر دور (250M تومان) |
 | `CommissionCalculationMethod` | "SP" | روش محاسبه = Stored Procedure |
 
 ---
@@ -158,3 +178,59 @@ flowchart TD
 | **Retry** | Polly — ۳ تلاش، backoff نمایی |
 | **فعال‌سازی** | فقط برای اعضای فعال باشگاه |
 | **وضعیت** | ✅ Production ready |
+
+---
+
+## ۹. کیف‌پول جادویی (Magic Wallet) ✅
+
+> **وضعیت: فاز ۱ تا ۵ پیاده‌سازی شده — فاز ۶ باقیمانده**  
+> **مرجع کامل:** [MAGIC-WALLET-SPEC](../roadmap/MAGIC-WALLET-SPEC.md)
+
+### ۹.۱ چرخه کامل
+
+```mermaid
+flowchart TD
+    A["خرید پکیج 56M\nBalance=56M, Discount=112M"] --> B["خرید از فروشگاه\nBalance کم می‌شود"]
+    B --> C{"Balance = 0?"}
+    C -->|خیر| B
+    C -->|بله| D{"عضو باشگاه فعال؟"}
+    D -->|خیر| E["حالت عادی باقی بمان"]
+    D -->|بله| F["🪄 ورود به حالت جادویی\nWalletMode = Magic"]
+    F --> G["شارژ از درگاه\nواریز × 2.5 = اعتبار Balance"]
+    G --> H{"Balance=0 AND\nTotalDeposited≥100M?"}
+    H -->|خیر| G
+    H -->|بله| I["خروج از جادویی\nWalletMode = Normal"]
+    I --> J["خرید مجدد پکیج\nفقط IPG — بدون دایا"]
+    J --> A
+```
+
+### ۹.۲ قوانین کلیدی
+
+| قانون | مقدار |
+|-------|-------|
+| ضریب شارژ | واریز × 2.5 = اعتبار Balance |
+| سقف واریز/دور | 100M تومان (1B ریال) |
+| سقف اعتبار/دور | 250M تومان (2.5B ریال) |
+| کمیسیون در Magic | ❌ غیرفعال |
+| شرط خروج | Balance=0 **و** TotalDeposited≥100M (هر دو همزمان) |
+| ریست سقف | هر خرید مجدد پکیج → سقف از صفر |
+
+### ۹.۳ Entity‌های جدید
+
+```csharp
+// فیلدهای جدید UserWallet
+public WalletMode WalletMode { get; set; }           // Normal=0, Magic=1
+public long MagicTotalDeposited { get; set; }         // مجموع واریزی دور فعلی
+public long MagicTotalCredited { get; set; }          // مجموع اعتبار دریافتی
+public DateTime? MagicActivatedAt { get; set; }
+public DateTime? MagicCompletedAt { get; set; }
+
+// Entity جدید — حل مشکل تاریخ کمیسیون
+public class ClubMembershipCycle {
+    public long Id { get; set; }
+    public long ClubMembershipId { get; set; }
+    public int CycleNumber { get; set; }               // شماره دور (1, 2, 3, ...)
+    public DateTime PackagePurchasedAt { get; set; }   // تاریخ خرید این دور
+    public bool IsCurrentCycle { get; set; }           // دور فعلی
+}
+```