إضافة وثائق عن آلية الزكاة - خوارزمية الغرف والصناديق

README.ar.md

@@ -57,6 +57,10 @@
 
 - المؤسسات المالية الإسلامية: دمج الزكاة (Zakat) في الأنظمة الحالية لتحسين الإدارة المالية وإعداد التقارير.
 
+### الوثائق
+
+- [آلية الزكاة: خوارزمية الغرف والصناديق](./docs/algorithm.ar.md)
+
 ### ابدأ الآن:
 
 قم بتثبيت مكتبة الزكاة (Zakat) باستخدام pip:

README.md

@@ -55,6 +55,10 @@ Zakat is a user-friendly Python library designed to simplify the tracking and ca
 
 - Islamic Financial Institutions: Integrate Zakat into existing systems for enhanced financial management and reporting.
 
+### Documentation
+
+- [Mechanism of Zakat: The Rooms and Boxes Algorithm](./docs/algorithm.md)
+
 ### Get Started:
 
 Install the Zakat library using pip:

docs/algorithm.ar.md

@@ -0,0 +1,68 @@
+<div dir="rtl">
+
+# آلية الزكاة: خوارزمية الغرف والصناديق
+
+تقدم خوارزمية "الغرف والصناديق" آلية مبتكرة لإدارة الحسابات المالية وحساب الزكاة بدقة. من خلال تقسيم الأموال إلى "غرف" و "صناديق" متميزة، تضمن هذه الطريقة الدقة والتتبع الشامل لالتزامات الزكاة.
+
+### شرح المفاهيم:
+
+**الغرف والصناديق:**
+
+- **الغرفة:** تعمل كحساب مالي منفصل.
+- **الصندوق:** يمثل كل معاملة مالية (إضافة أو خصم) داخل الغرفة. يتم تخزين البيانات الهامة مثل رأس المال الأولي وتاريخ المعاملة والرصيد المتبقي ودورات الزكاة وإجمالي الزكاة المدفوعة في الصندوق.
+
+### إدارة الأموال:
+
+**إضافة الأموال:**
+
+- في كل مرة يتم فيها إدخال الأموال إلى غرفة، يتم إنشاء صندوق جديد. يحتوي هذا الصندوق على تفاصيل المعاملة ويتم ترتيبه ترتيبًا زمنيًا إلى النانو ثانية لسجلات دقيقة.
+
+**خصم الأموال:**
+
+- لخصم الأموال، يتم فرز الصناديق بترتيب عكسي (الأحدث أولاً) لاستنفاد أحدث الصناديق أولاً. إذا تجاوزت الخصومات إجمالي النطاق المتبقي داخل الغرفة، يتم تشكيل صندوق جديد بقيمة سالبة للإشارة إلى الدين.
+
+**عمر الصندوق:**
+
+- تبدأ مدة الصندوق من إنشائه وتستمر حتى يصل رصيده إلى الصفر أو السالب. يستمر هذا العمر حتى لو تم نقل الأموال بين الغرف.
+
+### حساب الزكاة:
+
+**الزكاة على الصناديق:**
+
+- يتم تقييم كل صندوق للزكاة بشكل فردي بناءً على متطلبات "الحول" (سنة قمرية واحدة) و "النصاب" (الحد الأدنى).
+
+**الزكاة المجمعة:**
+
+- إذا استوفت الصناديق "الحول" ولكنها لم تصل بشكل فردي إلى "النصاب"، يتم تجميعها. إذا وصلت قيمتها الجماعية إلى "النصاب"، يتم احتساب الزكاة على المبلغ الإجمالي.
+
+**النصاب والحول:**
+
+- **النصاب:** يعتمد عادة على قيمة 85 جرامًا من الذهب أو 595 جرامًا من الفضة، ويمكن تعديلها حسب الحاجة.
+- **الحول:** يُعرَّف بأنه 355 يومًا.
+
+### مزايا الخوارزمية:
+
+- **المرونة:** توفر حساب زكاة مستمر ومتسلسل لكل صندوق.
+- **الأتمتة:** تخصم الزكاة تلقائيًا عند استيفاء المعايير.
+- **الشاملة:** تشمل جميع المعاملات المالية لحسابات زكاة دقيقة.
+- **قابلية التكيف:** تسمح بالتعديل في قيمة "النصاب" حسب الحاجة.
+
+### الميزات المحسنة:
+
+نظرًا للخصومات العديدة للصناديق، تقوم الخوارزمية بأتمتة العملية بالكامل. يتم عمل خصومات على الصندوق ذي الصلة تلقائيًا، وتسمح بتحصيل هذه الخصومات وخصمها من غرفة معينة أو غرف متعددة.
+
+على عكس الإطار الزمني السنوي الثابت للزكاة، تسمح هذه الخوارزمية بدفع الزكاة عدة مرات في اليوم إذا تم استيفاء الشروط، على غرار انتظام الصلوات.
+
+### اعتبارات هامة:
+
+- **"نصاب" الفضة:** بشكل افتراضي، تستخدم الخوارزمية "نصاب" الفضة نظرًا لقيمتها المنخفضة مقارنة بالذهب، مما يزيد من شمول دافعي الزكاة.
+- **انخفاض رأس المال بمرور الوقت:** يمكن للزكاة أن تقلل رأس المال بشكل كبير (حوالي 22٪ على مدى عقد من الزمان)؛ وبالتالي، يوصى بالاستثمارات التي تحافظ على رأس المال.
+
+### التحسينات المقترحة:
+
+- تطوير واجهة مستخدم سهلة الاستخدام لتسهيل إدارة الغرف والصناديق وتتبع الزكاة.
+- إنشاء تقارير مفصلة عن حسابات الزكاة والمدفوعات.
+- التكامل مع أنظمة المحاسبة الحالية لتبسيط حسابات الزكاة وتسجيلاتها.
+
+يضمن هذا النهج المنظم والمنهجي إدارة زكاة دقيقة وفعالة، والتكيف مع التعقيدات المالية الحديثة مع احترام الالتزامات التقليدية للإسلام.
+</div>

docs/algorithm.md

@@ -0,0 +1,65 @@
+# Mechanism of Zakat: The Rooms and Boxes Algorithm
+
+The "Rooms and Boxes" algorithm introduces an innovative mechanism for managing financial accounts and meticulously calculating Zakat. By breaking down finances into distinct "rooms" and "boxes," this method ensures accuracy and comprehensive tracking of Zakat obligations.
+
+### Breakdown of Concepts:
+
+**Rooms and Boxes:**
+
+- **Room:** Acts as a separate financial account.
+- **Box:** Represents each financial transaction (addition or deduction) within a room. Critical data such as the initial capital, the date of the transaction, remaining balance, Zakat cycles, and totals of Zakat paid are stored in the box.
+
+### Fund Management:
+
+**Adding Funds:**
+
+- Each time funds are introduced into a room, a new box is generated. This box houses the transaction specifics and is arranged chronologically to the nanosecond for precise records.
+
+**Deducting Funds:**
+
+- To deduct funds, the boxes are sorted in reverse (newest first) to deplete the most recent boxes first. Should deductions surpass the total remaining range within the room, a new box is formed with a negative value to indicate debt.
+
+**Box Lifespan:**
+
+- The duration of a box begins from its creation and persists until its balance hits zero or negative. This lifespan continues even if funds are moved between rooms.
+
+### Zakat Calculation:
+
+**Zakat on Boxes:**
+
+- Each box is evaluated for Zakat individually based on the "Hawl" (one lunar year) and "Nisab" (minimum threshold) requirements.
+
+**Aggregated Zakat:**
+
+- If boxes meet the "Hawl" but don't individually reach the "Nisab," they are grouped. If their collective value hits the "Nisab," Zakat is calculated on the combined amount.
+
+**Nisab and Hawl:**
+
+- **Nisab:** Typically based on the value of 85 grams of gold or 595 grams of silver, adjustable as required.
+- **Hawl:** Defined as 355 days.
+
+### Advantages of the Algorithm:
+
+- **Flexibility:** Offers continuous and sequential Zakat calculation for each box.
+- **Automation:** Automatically deducts Zakat when criteria are met.
+- **Comprehensiveness:** Encompasses all financial transactions for precise Zakat calculations.
+- **Adaptability:** Allows for adjustment in the "Nisab" value as needed.
+
+### Enhanced Features:
+
+Given the numerous box deductions, the algorithm automates the process entirely. Discounts are made on the relevant box automatically, and it allows the collection and deduction of these discounts from a specific room or multiple rooms.
+
+Unlike a fixed annual timeframe for Zakat, this algorithm enables Zakat to be payable multiple times a day if conditions are met, similar to the regularity of prayers.
+
+### Significant Considerations:
+
+- **Silver "Nisab":** By default, the algorithm uses the silver "Nisab" due to its lower value compared to gold, increasing the inclusivity of Zakat payers.
+- **Capital Decrease Over Time:** Zakat can decrease capital significantly (approximately 22% over a decade); thus, investments that preserve capital are recommended.
+
+### Suggested Enhancements:
+
+- Develop a user-friendly interface for easier room and box management and Zakat tracking.
+- Generate detailed reports on Zakat calculations and payments.
+- Integrate with existing accounting systems for streamlined Zakat calculations and recordings.
+
+This structured, methodical approach ensures accurate and effective Zakat management, adapting to modern financial complexities while honoring the traditional obligations of Islam.