diff --git a/README.md b/README.md
index a6bfbc7..0055a16 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,94 @@
-Blackjack, Slots, Mini Roulette, Coin Flip, Towers, Baccarat — all-in-one Discord bot.
+# 🎰 SupaCasino Discord Bot
+
+A cozy, all-in-one casino bot for a Discord server — **Blackjack**, **Slots**, **Mini Roulette**, **Coin Flip**, **Towers**, and **Baccarat** — with a shared wallet, daily bonuses, and slick button/modals UX.
+
+> fun, fast rounds, fair defaults, and simple controls.
+
+---
+
+## ✨ Features
+
+* **One wallet across all games** (SQLite; persists on disk)
+* **Modern UI** with buttons & modals (Set Bet, 2×, ½, Spin/Deal, etc.)
+* **Launcher:** `!casino` opens a clean game picker
+* **Economy:** `!daily`, `!topup`, `!tip @user <amount>`, `!balance`, `!leaderboard`
+* **Rules:** `!rules` brings in-game payout tables & guides
+* **Docker-ready** (one command to run)
+* **Extensible** (each game is a cog; easy to add more)
+
+---
+
+## 🚀 Quick Start
+
+### Option A — Docker (recommended)
+
+1. Copy the environment template and fill in your token:
 
-## Quick start (Docker)
 ```bash
 cp .env.example .env
-# edit .env and paste your DISCORD_TOKEN
+# open .env and paste your DISCORD_TOKEN
+```
+
+2. Build & run:
+
+```bash
 docker compose up -d --build
+```
+
+> SQLite database is stored at `./data/blackjack.db` (mounted into the container).
+
+### Option B — Local Python
+
+```bash
+python -m venv .venv
+. .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+cp .env.example .env  # add your DISCORD_TOKEN
+python -m src.bot
+```
+
+---
+
+## 🧭 Commands
+
+* **Hub**
+
+  * `!casino` — open game launcher (self-cleans on click)
+  * `!rules` — open rules menu
+* **Economy**
+
+  * `!balance` / `!bal` — your stats (W/L per game, nets, spins)
+  * `!leaderboard` / `!lb` — top cash
+  * `!daily` — claim daily bonus (cash + free spins)
+  * `!topup` — faucet every 5 minutes
+  * `!tip @user 500` — send cash to a friend
+* **Games** (also available from `!casino`)
+
+  * `!blackjack` — panel with **Set Bet · 2× · ½ · Deal** then **Hit/Stand/Double/Split**
+  * `!slots` — **Set Bet** + **Lines (1/3/5/8)** + **Spin Again**
+    ⭐ acts as wildcard for exactly “2 of a kind + 1 ⭐”; ⭐⭐⭐ on middle row gives bonus spins.
+  * `!roulette` — mini roulette with bet builder & spin again
+  * `!coin` — coin flip with Set Bet + Heads/Tails (repeatable)
+  * `!towers` — 9 tiers, 5 difficulties, pick tiles, cash out or risk it
+  * `!baccarat` — Player/Tie/Banker bet modals + Deal (5% banker commission)
+
+---
+
+## ⚙️ Configuration
+
+Tunables live in **`src/utils/constants.py`** (can be overwritten in `.env`):
+
+| Setting (env / constant)                 | What it does                               | Default                  |
+| ---------------------------------------- | ------------------------------------------ | ------------------------ |
+| `DISCORD_TOKEN` (env)                    | Your bot token                             | –                        |
+| `DB_PATH` (env)                          | SQLite path (inside container)             | `/app/data/blackjack.db` |
+| `DAILY_CASH`, `DAILY_FREE_SPINS`         | Daily bonus values                         | `10000`, `3`             |
+| `TOPUP_AMOUNT`, `TOPUP_COOLDOWN_MINUTES` | Faucet amount & cooldown                   | `100`, `5`               |
+| Slots: `SLOTS_MIN_BET`, `SLOTS_MAX_BET`  | Bet limits                                 | sensible defaults        |
+| Slots: `PAYOUTS`, `WEIGHTS`              | 3-in-a-row payouts and symbol rarity       | tuned                    |
+| Slots: `WILDCARD_FACTOR`                 | ⭐ wildcard payout scale (reduced)          | `0.x`                    |
+| Towers: `TOWERS_EDGE_PER_STEP`           | per-step house edge applied to multipliers | small                    |
+| Baccarat: `BANKER_COMMISSION`            | Banker commission                          | `0.05`                   |
+
+> Change safely, restart the bot, and you’re set.
+