diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2b39fbd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,282 @@
+# Hesabix - سیستم حسابداری جامع
+
+Hesabix یک سیستم حسابداری کامل و مدرن است که شامل یک API قدرتمند (FastAPI + SQLAlchemy) و رابط کاربری زیبا (Flutter) می‌باشد. این سیستم برای مدیریت مالی کسب‌وکارهای کوچک و متوسط طراحی شده است.
+
+## ویژگی‌های اصلی
+
+### 🚀 API Backend (hesabixAPI)
+- **FastAPI** - فریمورک مدرن و سریع برای ساخت API
+- **SQLAlchemy** - ORM قدرتمند برای مدیریت پایگاه داده
+- **MySQL** - پایگاه داده رابطه‌ای قابل اعتماد
+- **Alembic** - مدیریت migration های پایگاه داده
+- **Pydantic** - اعتبارسنجی و سریالیزاسیون داده‌ها
+- **JWT Authentication** - سیستم احراز هویت امن
+- **Multi-language Support** - پشتیبانی از چندین زبان (فارسی/انگلیسی)
+- **Jalali Calendar** - تقویم شمسی برای کاربران ایرانی
+
+### 📱 Frontend (hesabixUI)
+- **Flutter** - فریمورک کراس‌پلتفرم برای موبایل، وب و دسکتاپ
+- **Material Design** - رابط کاربری مدرن و زیبا
+- **Responsive Design** - سازگار با تمام اندازه‌های صفحه
+- **Multi-platform** - اجرا روی Android، iOS، Web و Desktop
+- **Persian Font Support** - پشتیبانی کامل از فونت فارسی (Vazirmatn)
+
+## ساختار پروژه
+
+```
+hesabix/
+├── hesabixAPI/          # Backend API (FastAPI)
+│   ├── app/            # کد اصلی اپلیکیشن
+│   ├── adapters/       # لایه‌های دسترسی به داده
+│   ├── migrations/     # فایل‌های migration پایگاه داده
+│   └── tests/          # تست‌های واحد
+├── hesabixUI/          # Frontend (Flutter)
+│   └── hesabix_ui/     # پروژه Flutter اصلی
+├── docs/               # مستندات پروژه
+└── scripts/            # اسکریپت‌های کمکی
+```
+
+## پیش‌نیازها
+
+### برای Backend (API)
+- Python 3.11+
+- MySQL 8.0+
+- pip (Python package manager)
+
+### برای Frontend (UI)
+- Flutter SDK 3.9.2+
+- Dart SDK
+- Git
+
+### برای Linux Desktop
+- GTK+ 3.0 development libraries
+- CMake
+- Ninja build system
+- C++ compiler (clang++ یا gcc)
+
+## نصب و راه‌اندازی
+
+### 1. کلون کردن پروژه
+
+```bash
+git clone <repository-url>
+cd hesabix
+```
+
+### 2. راه‌اندازی Backend (API)
+
+```bash
+# ورود به دایرکتوری API
+cd hesabixAPI
+
+# ایجاد محیط مجازی
+python3 -m venv .venv
+source .venv/bin/activate  # در Windows: .venv\Scripts\activate
+
+# نصب وابستگی‌ها
+pip install -e .[dev]
+
+# کپی کردن فایل تنظیمات
+cp env.example .env
+
+# ویرایش فایل .env و تنظیم اطلاعات پایگاه داده
+# DB_USER=root
+# DB_PASSWORD=your_password
+# DB_HOST=localhost
+# DB_PORT=3306
+# DB_NAME=hesabixpy
+
+# اجرای migration ها
+alembic upgrade head
+
+# اجرای سرور API
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### 3. راه‌اندازی Frontend (UI)
+
+```bash
+# ورود به دایرکتوری UI
+cd hesabixUI/hesabix_ui
+
+# نصب وابستگی‌ها
+flutter pub get
+
+# اجرای اپلیکیشن
+flutter run
+```
+
+## اسکریپت‌های کمکی
+
+پروژه شامل چندین اسکریپت کمکی برای سهولت در استفاده است:
+
+### اجرای API محلی
+```bash
+./run_local.sh serve    # اجرای سرور API
+./run_local.sh migrate  # اجرای migration ها
+./run_local.sh test     # اجرای تست‌ها
+```
+
+### اجرای Flutter Web
+```bash
+./run_web.sh                    # اجرای وب اپلیکیشن
+./run_web.sh --port 8081        # اجرا روی پورت مشخص
+./run_web.sh --mode debug       # اجرا در حالت debug
+```
+
+### اجرای Flutter Linux Desktop
+```bash
+./run_linux.sh                  # اجرای دسکتاپ اپلیکیشن
+./run_linux.sh --mode release   # اجرا در حالت release
+./run_linux.sh --clean          # پاک کردن build و اجرای مجدد
+```
+
+## تنظیمات محیط
+
+### متغیرهای محیطی API (.env)
+
+```env
+# تنظیمات عمومی
+APP_NAME=Hesabix API
+ENVIRONMENT=development
+DEBUG=true
+API_V1_PREFIX=/api/v1
+APP_VERSION=0.1.0
+
+# پایگاه داده
+DB_USER=root
+DB_PASSWORD=your_password
+DB_HOST=localhost
+DB_PORT=3306
+DB_NAME=hesabixpy
+SQLALCHEMY_ECHO=false
+
+# لاگ‌گیری
+LOG_LEVEL=INFO
+```
+
+### تنظیمات Flutter
+
+برای تنظیم آدرس API در Flutter، از متغیر محیطی استفاده کنید:
+
+```bash
+flutter run --dart-define API_BASE_URL=http://localhost:8000
+```
+
+## API Endpoints
+
+### احراز هویت
+- `POST /api/v1/auth/login` - ورود کاربر
+- `POST /api/v1/auth/register` - ثبت نام کاربر
+- `POST /api/v1/auth/refresh` - تمدید توکن
+
+### سلامت سیستم
+- `GET /api/v1/health` - بررسی وضعیت API
+
+### کسب‌وکار
+- `GET /api/v1/businesses` - لیست کسب‌وکارها
+- `POST /api/v1/businesses` - ایجاد کسب‌وکار جدید
+- `PUT /api/v1/businesses/{id}` - ویرایش کسب‌وکار
+
+### محصولات
+- `GET /api/v1/products` - لیست محصولات
+- `POST /api/v1/products` - ایجاد محصول جدید
+- `PUT /api/v1/products/{id}` - ویرایش محصول
+
+### فاکتورها و پرداخت‌ها
+- `GET /api/v1/receipts` - لیست فاکتورها
+- `POST /api/v1/receipts` - ایجاد فاکتور جدید
+- `GET /api/v1/payments` - لیست پرداخت‌ها
+
+## ویژگی‌های خاص
+
+### تقویم شمسی
+سیستم از تقویم شمسی پشتیبانی کامل می‌کند و تمام تاریخ‌ها به صورت خودکار تبدیل می‌شوند.
+
+### چندزبانه
+- پشتیبانی از زبان‌های فارسی و انگلیسی
+- امکان اضافه کردن زبان‌های جدید
+- ترجمه خودکار رابط کاربری
+
+### امنیت
+- احراز هویت JWT
+- رمزگذاری رمز عبور با Argon2
+- اعتبارسنجی ورودی‌ها
+- محافظت در برابر SQL Injection
+
+## توسعه و مشارکت
+
+### اجرای تست‌ها
+```bash
+# تست‌های Backend
+cd hesabixAPI
+pytest
+
+# تست‌های Frontend
+cd hesabixUI/hesabix_ui
+flutter test
+```
+
+### کد استایل
+```bash
+# Backend
+black .
+ruff check .
+
+# Frontend
+flutter analyze
+```
+
+### ساخت برای تولید
+```bash
+# ساخت API
+cd hesabixAPI
+pip install -e .
+
+# ساخت Flutter
+cd hesabixUI/hesabix_ui
+flutter build web
+flutter build linux
+flutter build apk
+```
+
+## عیب‌یابی
+
+### مشکلات رایج
+
+1. **خطای اتصال به پایگاه داده**
+   - بررسی تنظیمات .env
+   - اطمینان از اجرای MySQL
+   - بررسی دسترسی‌های کاربر
+
+2. **مشکلات Flutter**
+   - اجرای `flutter clean`
+   - حذف پوشه build
+   - اجرای مجدد `flutter pub get`
+
+3. **مشکلات Linux Desktop**
+   - نصب وابستگی‌های مورد نیاز
+   - استفاده از اسکریپت `run_linux.sh`
+
+### لاگ‌ها
+- API logs: در کنسول سرور نمایش داده می‌شوند
+- Flutter logs: با `flutter logs` قابل مشاهده است
+
+## مجوز
+
+این پروژه تحت مجوز [MIT License](LICENSE) منتشر شده است.
+
+## پشتیبانی
+
+برای گزارش باگ یا درخواست ویژگی جدید، لطفاً issue جدیدی در repository ایجاد کنید.
+
+## تیم توسعه
+
+- **Backend**: FastAPI + SQLAlchemy + MySQL
+- **Frontend**: Flutter + Material Design
+- **DevOps**: Docker + Scripts
+- **Documentation**: Markdown + Persian
+
+---
+
+**Hesabix** - سیستم حسابداری مدرن برای کسب‌وکارهای ایرانی 🇮🇷