admin/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify Magic Wallet cap is per-cycle, not lifetime

Browse Source 
- 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
This commit is contained in:
masoodafar-web
2026-02-19 02:17:10 +03:30
parent a94d0dbe95
commit 2f0d43aa81
2 changed files with 64 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
roadmap/MAGIC-WALLET-PLAN.md
+2
View File
@@ -47,6 +47,8 @@
- سناریو ۱: Balance=0 بعد از خرید → WalletMode=Magic ✅ - سناریو ۱: Balance=0 بعد از خرید → WalletMode=Magic ✅
- سناریو ۲: بدون پکیج + Balance=0 → نباید Magic بشه ❌ - سناریو ۲: بدون پکیج + Balance=0 → نباید Magic بشه ❌
- سناریو ۳: Magic + Balance=0 + TotalDeposited>0 → خروج ✅ - سناریو ۳: Magic + Balance=0 + TotalDeposited>0 → خروج ✅
- سناریو ۴: خروج از Magic → خرید مجدد پکیج → Balance=0 → Magic مجدد با **سقف ریست‌شده** ✅
- سناریو ۵: دور دوم → TotalDeposited, TotalCredited = 0 (ریست) ✅
--- ---
roadmap/MAGIC-WALLET-SPEC.md
+62 -10
View File
@@ -10,6 +10,8 @@
کاربر بعد از خرید پکیج پایه (۵۶M) و خرج کردن کامل Balance از فروشگاه عادی، وارد **حالت جادویی** می‌شه. در این حالت می‌تونه کیف‌پولش رو از درگاه شارژ کنه و **۲.۵ برابر** اعتبار بگیره — بدون هیچ کمیسیون یا پورسانتی. کاربر بعد از خرید پکیج پایه (۵۶M) و خرج کردن کامل Balance از فروشگاه عادی، وارد **حالت جادویی** می‌شه. در این حالت می‌تونه کیف‌پولش رو از درگاه شارژ کنه و **۲.۵ برابر** اعتبار بگیره — بدون هیچ کمیسیون یا پورسانتی.
> ⚠️ **سقف ۱۰۰M ورودی / ۲۵۰M خروجی per-cycle هست** — هر بار که کاربر دوباره پکیج ۵۶M بخره و وارد Magic بشه، سقف ریست میشه. این چرخه تا بی‌نهایت تکرار میشه.
```mermaid ```mermaid
stateDiagram-v2 stateDiagram-v2
[*] --> NewUser: ثبت‌نام [*] --> NewUser: ثبت‌نام
@@ -77,16 +79,19 @@ stateDiagram-v2
## ۳. قوانین Magic Mode ## ۳. قوانین Magic Mode
### ۳.۱ ضریب و سقف ### ۳.۱ ضریب و سقف (per-cycle)
| پارامتر | مقدار | ثابت پیشنهادی | | پارامتر | مقدار | ثابت پیشنهادی | اسکوپ |
|----------|-------|---------------| |----------|-------|---------------|--------|
| ضریب شارژ | **×2.5** | `MagicWalletMultiplier = 2.5m` | | ضریب شارژ | **×2.5** | `MagicWalletMultiplier = 2.5m` | — |
| سقف ورودی | **100M تومان** (1B ریال) | `MagicWalletMaxDeposit = 1_000_000_000` | | سقف ورودی | **100M تومان** (1B ریال) | `MagicWalletMaxDeposit = 1_000_000_000` | **هر دور** |
| سقف خروجی | **250M تومان** (2.5B ریال) | `MagicWalletMaxCredit = 2_500_000_000` | | سقف خروجی | **250M تومان** (2.5B ریال) | `MagicWalletMaxCredit = 2_500_000_000` | **هر دور** |
| سود کاربر | **150%** | — | | سود کاربر | **150%** | — | — |
### ۳.۲ مثال عددی > 🔄 **سقف per-cycle هست نه lifetime.** هر بار که کاربر از Magic خارج بشه و دوباره پکیج ۵۶M بخره،
> `MagicTotalDeposited` و `MagicTotalCredited` به **صفر ریست** میشن و یه دور جدید شروع میشه.
### ۳.۲ مثال عددی (یک شارژ)
``` ```
واریز: 10,000,000 تومان (100M ریال) واریز: 10,000,000 تومان (100M ریال)
@@ -95,13 +100,45 @@ stateDiagram-v2
├── اعتبار نهایی: 25,000,000 تومان (Balance += 250M ریال) ├── اعتبار نهایی: 25,000,000 تومان (Balance += 250M ریال)
└── WalletChangeLog: BalanceChange = +250,000,000 ریال ✅ └── WalletChangeLog: BalanceChange = +250,000,000 ریال ✅
سقف: سقف (این دور):
├── مجموع واریزی: MagicTotalDeposited += 100,000,000 ریال ├── مجموع واریزی: MagicTotalDeposited += 100,000,000 ریال
├── مجموع اعتبار: MagicTotalCredited += 250,000,000 ریال ├── مجموع اعتبار: MagicTotalCredited += 250,000,000 ریال
└── باقیمانده سقف: MaxDeposit - TotalDeposited └── باقیمانده سقف: 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 | | قابلیت | Normal Mode | Magic Mode |
|--------|-------------|------------| |--------|-------------|------------|
@@ -145,6 +182,21 @@ stateDiagram-v2
└── user.PurchaseCycleCount++ └── user.PurchaseCycleCount++
``` ```
### ۴.۳ ریست سقف در دور بعدی
```
وقتی کاربر دوباره پکیج ۵۶M بخره و Balance=0 بشه → Magic Mode:
├── MagicTotalDeposited = 0 ← ریست!
├── MagicTotalCredited = 0 ← ریست!
├── MagicActivatedAt = now ← زمان جدید
└── MagicCompletedAt = null ← پاک میشه
⚠️ سقف per-cycle هست:
├── هر دور: حداکثر 100M واریز → 250M اعتبار
├── تعداد دور: بی‌نهایت (تا وقتی پکیج بخره)
└── PurchaseCycleCount: فقط برای ترک تعداد دورها (محدودیت نداره)
```
--- ---
## ۵. تراکنش‌ها و لاگ ## ۵. تراکنش‌ها و لاگ